Message dispatcher. More...
#include <kanzi/platform/platform.hpp>
#include <kanzi/platform/chrono.hpp>
#include <kanzi/object/metaclass.hpp>
#include <kanzi/message/message_type.hpp>
#include <kanzi/message/message_arguments.hpp>
#include <system/kzs_types.h>
#include <system/debug/kzs_error.h>
#include <kanzi/platform/memory.hpp>
#include "kzu_message_dispatcher_properties.h"
Namespaces | |
kanzi | |
Macros | |
#define | KZU_MESSAGE_DISPATCHER_NO_LIMIT |
A constant for kzuMessageDispatcherSetMessageLimit indicating that no message limit should be used. More... | |
Typedefs | |
typedef kzsError(* | KzuMessageHandlerFunction )(struct kanzi::MessageArguments *message, void *userData) |
Message callback prototype. More... | |
typedef kzsError(* | KzuMessageDispatchFunction )(const kanzi::MessageArguments *message, void *userData) |
Application message callback prototype. More... | |
typedef function< void(const TimerMessageArguments &)> | kanzi::TimerFunction |
typedef shared_ptr< void > | kanzi::TimerSubscriptionToken |
Enumerations | |
enum | KzuTimerMessageMode { KZU_TIMER_MESSAGE_MODE_ONCE, KZU_TIMER_MESSAGE_MODE_REPEAT, KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH } |
Timer mode. More... | |
Functions | |
KANZI_API kzsError | kzuMessageDispatcherCreate (const struct KzcMemoryManager *memoryManager, struct KzuMessageDispatcher **out_messageDispatcher) |
Create a message dispatcher. More... | |
KANZI_API kzsError | kzuMessageDispatcherDelete (struct KzuMessageDispatcher *messageDispatcher) |
Destroy a message dispatcher. More... | |
KANZI_API void | kzuMessageDispatcherSetInputManager (struct KzuMessageDispatcher *messageDispatcher, kanzi::KzuInputManager *inputManager) |
Set an input manager for a dispatcher. More... | |
KANZI_API struct kanzi::KzuInputManager * | kzuMessageDispatcherGetInputManager (const struct KzuMessageDispatcher *messageDispatcher) |
Get the input manager from a dispatcher. More... | |
KANZI_API void | kzuMessageDispatcherSetTaskScheduler (struct KzuMessageDispatcher *messageDispatcher, struct KzuTaskScheduler *taskScheduler) |
Set a task scheduler for a dispatcher. More... | |
KANZI_API struct KzuTaskScheduler * | kzuMessageDispatcherGetTaskScheduler (const struct KzuMessageDispatcher *messageDispatcher) |
Get the task scheduler from a dispatcher. More... | |
KANZI_API void | kzuMessageDispatcherSetMessageLimit (struct KzuMessageDispatcher *messageDispatcher, kzUint limitThreshold, kzUint limitPerFrame) |
Sets the limitation of how many messages can be processed per frame. More... | |
KANZI_API kzsError | kzuMessageDispatcherAddHandler (const struct KzuMessageDispatcher *messageDispatcher, kanzi::Node *subscriptionSiteNode, const struct KzuMessageType *messageType, kanzi::Node *messageSource, KzuMessageHandlerFunction handlerFunction, void *userData) |
Adds a message handler. More... | |
KANZI_API kzsError | kzuMessageDispatcherAddTunnellingHandler (const struct KzuMessageDispatcher *messageDispatcher, kanzi::Node *subscriptionSiteNode, const struct KzuMessageType *messageType, kanzi::Node *messageSource, KzuMessageHandlerFunction handlerFunction, void *userData) |
Adds a message handler for tunneling phase. More... | |
KANZI_API kzsError | kzuMessageDispatcherIsHandlerSubscriptionValid (const struct KzuMessageDispatcher *messageDispatcher, const kanzi::Node *subscriptionSiteNode, const struct KzuMessageType *messageType, KzuMessageHandlerFunction handlerFunction, const void *userData, kzBool *out_valid) |
Checks if a handler subscription is valid. More... | |
KANZI_API kzsError | kzuMessageDispatcherRemoveHandler (const struct KzuMessageDispatcher *messageDispatcher, const kanzi::Node *subscriptionSiteNode, const struct KzuMessageType *messageType, KzuMessageHandlerFunction handlerFunction, const void *userData) |
Removes a message handler. More... | |
KANZI_API kzsError | kzuMessageDispatcherDispatchMessage (struct KzuMessageDispatcher *messageDispatcher, struct kanzi::MessageArguments *message, kanzi::Node *source) |
Dispatches a message. More... | |
KANZI_API kzsError | kzuMessageDispatcherDispatchMessageAsync_internal (struct KzuMessageDispatcher *messageDispatcher, struct kanzi::MessageArguments *message, kanzi::Node *source) |
Dispatches a message. More... | |
KANZI_API kzsError | kzuMessageDispatcherDispatchQueuedMessages (struct KzuMessageDispatcher *messageDispatcher, kzUint elapsedTime=0) |
Dispatches queued messages. More... | |
KANZI_API kzsError | kzuMessageDispatcherNotifyObjectDeleted (const struct KzuMessageDispatcher *messageDispatcher, const kanzi::Node *objectNode) |
Notifies the message dispatcher that an object node is being destroyed. More... | |
KANZI_API kzsError | kzuMessageDispatcherAddTimerHandler (KzuMessageDispatcher *messageDispatcher, kzUint interval, enum KzuTimerMessageMode mode, KzuMessageHandlerFunction handlerFunction, void *userData) |
Registers a timer handler. More... | |
KANZI_API kzsError | kzuMessageDispatcherRemoveTimerHandler (KzuMessageDispatcher *messageDispatcher, KzuMessageHandlerFunction handlerFunction, const void *userData) |
Unregisters a timer handler. More... | |
KANZI_API kzUint | kzuMessageDispatcherGetTime (const struct KzuMessageDispatcher *messageDispatcher) |
Returns current time of message dispatcher in milliseconds. More... | |
KANZI_API TimerSubscriptionToken | kanzi::addTimerHandler (KzuMessageDispatcher *messageDispatcher, chrono::milliseconds interval, KzuTimerMessageMode mode, TimerFunction callback) |
KANZI_API void | kanzi::removeTimerHandler (KzuMessageDispatcher *messageDispatcher, TimerSubscriptionToken token) |
Message dispatcher.
Provides a system to exchange messages between different parts of an application. Messages can be used to notify of an event or request operations and data.
Copyright 2008-2020 by Rightware. All rights reserved.
#define KZU_MESSAGE_DISPATCHER_NO_LIMIT |
A constant for kzuMessageDispatcherSetMessageLimit indicating that no message limit should be used.
typedef kzsError(* KzuMessageHandlerFunction)(struct kanzi::MessageArguments *message, void *userData) |
Message callback prototype.
typedef kzsError(* KzuMessageDispatchFunction)(const kanzi::MessageArguments *message, void *userData) |
Application message callback prototype.
enum KzuTimerMessageMode |
Timer mode.
KANZI_API kzsError kzuMessageDispatcherCreate | ( | const struct KzcMemoryManager * | memoryManager, |
struct KzuMessageDispatcher ** | out_messageDispatcher | ||
) |
Create a message dispatcher.
KANZI_API kzsError kzuMessageDispatcherDelete | ( | struct KzuMessageDispatcher * | messageDispatcher | ) |
Destroy a message dispatcher.
KANZI_API void kzuMessageDispatcherSetInputManager | ( | struct KzuMessageDispatcher * | messageDispatcher, |
kanzi::KzuInputManager * | inputManager | ||
) |
Set an input manager for a dispatcher.
KANZI_API struct kanzi::KzuInputManager* kzuMessageDispatcherGetInputManager | ( | const struct KzuMessageDispatcher * | messageDispatcher | ) |
Get the input manager from a dispatcher.
KANZI_API void kzuMessageDispatcherSetTaskScheduler | ( | struct KzuMessageDispatcher * | messageDispatcher, |
struct KzuTaskScheduler * | taskScheduler | ||
) |
Set a task scheduler for a dispatcher.
KANZI_API struct KzuTaskScheduler* kzuMessageDispatcherGetTaskScheduler | ( | const struct KzuMessageDispatcher * | messageDispatcher | ) |
Get the task scheduler from a dispatcher.
KANZI_API void kzuMessageDispatcherSetMessageLimit | ( | struct KzuMessageDispatcher * | messageDispatcher, |
kzUint | limitThreshold, | ||
kzUint | limitPerFrame | ||
) |
Sets the limitation of how many messages can be processed per frame.
If the number of messages exceeds limitThreshold, a warning is logged and the remaining messages are discarded. KZU_MESSAGE_DISPATCHER_NO_LIMIT disables the limitation (default). After the threshold has been exceeded once, subsequent frames will process at most limitPerFrame messages to ensure good framerate.
KANZI_API kzsError kzuMessageDispatcherAddHandler | ( | const struct KzuMessageDispatcher * | messageDispatcher, |
kanzi::Node * | subscriptionSiteNode, | ||
const struct KzuMessageType * | messageType, | ||
kanzi::Node * | messageSource, | ||
KzuMessageHandlerFunction | handlerFunction, | ||
void * | userData | ||
) |
Adds a message handler.
messageDispatcher | The message dispatcher to use. |
subscriptionSiteNode | Object node that is associated with the message subscription created by this function. |
messageType | Type of the message to match. |
messageSource | Source of the message (as returned by kzuMessageGetSource) to match. |
handlerFunction | Function to call when a matching message appears. |
userData | User data pointer passed to handlerFunction. |
KANZI_API kzsError kzuMessageDispatcherAddTunnellingHandler | ( | const struct KzuMessageDispatcher * | messageDispatcher, |
kanzi::Node * | subscriptionSiteNode, | ||
const struct KzuMessageType * | messageType, | ||
kanzi::Node * | messageSource, | ||
KzuMessageHandlerFunction | handlerFunction, | ||
void * | userData | ||
) |
Adds a message handler for tunneling phase.
KANZI_API kzsError kzuMessageDispatcherIsHandlerSubscriptionValid | ( | const struct KzuMessageDispatcher * | messageDispatcher, |
const kanzi::Node * | subscriptionSiteNode, | ||
const struct KzuMessageType * | messageType, | ||
KzuMessageHandlerFunction | handlerFunction, | ||
const void * | userData, | ||
kzBool * | out_valid | ||
) |
Checks if a handler subscription is valid.
KANZI_API kzsError kzuMessageDispatcherRemoveHandler | ( | const struct KzuMessageDispatcher * | messageDispatcher, |
const kanzi::Node * | subscriptionSiteNode, | ||
const struct KzuMessageType * | messageType, | ||
KzuMessageHandlerFunction | handlerFunction, | ||
const void * | userData | ||
) |
Removes a message handler.
KANZI_API kzsError kzuMessageDispatcherDispatchMessage | ( | struct KzuMessageDispatcher * | messageDispatcher, |
struct kanzi::MessageArguments * | message, | ||
kanzi::Node * | source | ||
) |
Dispatches a message.
The associated handlers are called immediately.
KANZI_API kzsError kzuMessageDispatcherDispatchMessageAsync_internal | ( | struct KzuMessageDispatcher * | messageDispatcher, |
struct kanzi::MessageArguments * | message, | ||
kanzi::Node * | source | ||
) |
Dispatches a message.
The associated handlers are called when kzuMessageDispatcherDispatchQueuedMessages is called.
KANZI_API kzsError kzuMessageDispatcherDispatchQueuedMessages | ( | struct KzuMessageDispatcher * | messageDispatcher, |
kzUint | elapsedTime = 0 |
||
) |
Dispatches queued messages.
Generally should be called once per frame.
KANZI_API kzsError kzuMessageDispatcherNotifyObjectDeleted | ( | const struct KzuMessageDispatcher * | messageDispatcher, |
const kanzi::Node * | objectNode | ||
) |
Notifies the message dispatcher that an object node is being destroyed.
This will cancel all messages where the specified node is the source of the message or the current site during routing.
KANZI_API kzsError kzuMessageDispatcherAddTimerHandler | ( | KzuMessageDispatcher * | messageDispatcher, |
kzUint | interval, | ||
enum KzuTimerMessageMode | mode, | ||
KzuMessageHandlerFunction | handlerFunction, | ||
void * | userData | ||
) |
Registers a timer handler.
messageDispatcher | The message dispatcher to use. |
interval | timeout in milliseconds in case of a one-shot timer, and the interval in case of a repeating timer. |
mode | KZU_TIMER_MESSAGE_MODE_ONCE, KZU_TIMER_MESSAGE_MODE_REPEAT or KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH. KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH is recommended for a repeating timer because it calls handlerFunction only once when the interval has been exceeded several times over. |
handlerFunction | The function to call when the timer expires. |
userData | User data pointer passed to handlerFunction. |
KANZI_API kzsError kzuMessageDispatcherRemoveTimerHandler | ( | KzuMessageDispatcher * | messageDispatcher, |
KzuMessageHandlerFunction | handlerFunction, | ||
const void * | userData | ||
) |
Unregisters a timer handler.
KANZI_API kzUint kzuMessageDispatcherGetTime | ( | const struct KzuMessageDispatcher * | messageDispatcher | ) |
Returns current time of message dispatcher in milliseconds.